\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Basic User Interface Functions}

\beginChapter 2.{Common Lisp Object System Specification}%
{Basic User Interface Functions}{Basic User Interface Functions}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}
This chapter describes the functions provided by
the \CLOS\ Basic User Interface.
\vfill
\endSection%{Introduction}


\begincom{add-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf add-method} adds a method to a generic function.  It
modifies the specified generic function and returns the modified
generic function as its result.

\label Syntax:

\Defgen {add-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.  If there is no such generic 
function, an error is signalled.

The {\it method\/} argument is a method object.  The argument list of
the method function must be congruent with the argument lists of any
other methods associated with the generic function or with the
lambda list of the generic function.
%[i.e., if there are no other methods, then a defgeneric or
%make-generic must have been performed.  better way to say this?]

\label Values:

The modified generic function is returned as the result of {\bf add-method}.
The resulting generic function is {\bf eq} to the generic function specified
by the {\it generic-function\/} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the given method is already one of the methods of the generic
function or if the method corresponds in argument specializers and
method combination identifiers to an existing method of the generic
function, an error is signalled.

%Note that a given method may be a method on more than one generic
%function.

\label See Also:

{\bf defmethod

make-method

make-generic-function

defgeneric-options}

\endcom


\begincom{argument-precedence-order}\ftype{Generic function}

\label Purpose:

The generic function {\bf argument-precedence-order} returns an
association list.  Each pair in this association list consists of
a parameter name and an integer that indicates the position of the
corresponding argument in the precedence order.  A value of 0
indicates the highest precedence.

\label Syntax:

\Defgen {argument-precedence-order} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a symbol
that names a generic function.

\label Values:

The result is an association list whose pairs consist of a parameter name
and an integer that indicates the precedence of the corresponding argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{call-next-method}\ftype{Macro}

\label Purpose:

[The description of {\bf call-next-method} will be rewritten once
we have decided on method combination.]

The macro {\bf call-next-method} is used within the body of a
method.  It calls the ``next method" with the same arguments that the
current method received.
%  [The definition of ``next method'' should
% be given in this sentence and the next paragraph deleted.]
If there is no next method an error is signalled.

For the precise definition of ``next method" see the section ``Method
Selection and Combination".

The macro {\bf call-next-method} returns the value or
values returned by the method it calls.  

Further computation after {\bf call-next-method} returns is possible,
so this provides a general imperative form of method combination.
%  [I would omit this sentence--what is {\it imperative\/} method combination?]

The type of method combination in use determines in which kinds of methods 
{\bf call-next-method} may to be used.  The default method combination
type, {\bf :daemon}, allows {\bf call-next-method} to be called from within
primary methods and {\bf :around} methods.  

If you define a new type of method combination using the short form of
{\bf define-method-combination}, {\bf call-next-method} can be done in
{\bf :around} methods only. % [??]

\label Syntax:

\Defmac {call-next-method} {}

\label Arguments:

The macro {\bf call-next-method} is called with no arguments.

\label Values:

The macro {\bf call-next-method} returns the value or values
returned by the method it calls.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

Neither argument defaulting, nor the use of {\bf setq} or {\bf let} on 
variables with the same names as parameters affects {\bf call-next-method}.
% [??]

Possible extensions: % [have we discussed any of this ?]

{\bf call-next-method} {\it arguments\/}  When at least one argument is
given, {\bf call-next-method} supplies those
arguments instead of the arguments that this method received.  

{\bf apply-next-method} {\it arguments\/} This is like {\bf
call-next-method} except that it uses {\bf apply} instead of {\bf
funcall}.  That is, the last argument is really a list of arguments.

%\label See Also:

%See the sections ``Method Selection'' and ``Method Combination.''

\endcom



\begincom{change-class}\ftype{Function}

\label Purpose:

The function {\bf change-class} changes the class of an instance to the
new class.  It destructively modifies and returns the instance.

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument is any object.

The {\it new-class\/} argument is a class object.

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[The internal protocol of {\bf change-class} needs to be spec'd.]

[The function {\bf change-class} currently supports changing the class
only of instances of metaclass {\bf class}.  The internal protocol of
{\bf change-class} will provide for extensions to other metaclasses.]

\endcom



\begincom{class-of}\ftype{Function}

\label Purpose:

The function {\bf class-of} returns the class object for the most
specific class of which the given object is an instance.  Every Common
Lisp object has a class.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:

The function {\bf class-of} returns the class object that represents the
most specific class of which the  argument is an instance.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
built-in-class} or a subclass of {\bf built-in-class} (other
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

Note that {\bf class-of} can never return an abstract class.

\endcom



\begincom{defclass}\ftype{Macro}

\label Purpose:

The macro {\bf defclass} defines a new class.  It returns the name of
the new class as its result.

The syntax of {\bf defclass} provides options for specifying default
initialization values for slots and for requesting that functions be
automatically generated to read and write the values of slots and to
construct new instances.  No accessor, reader, or constructor
functions are defined by default: their generation must be explicitly
requested.  No initial slot values are provided by default.

Defining a new class also causes a type of the same name to be
defined.  The predicate {\tt (typep {\it object class-name\/})}
will be true if the given object is an instance of the new class.

\eject
\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{super-class-name}}}
\paren{\star{\curly{slot-spec}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it super-class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-spec\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \star{\curly{slot-option}})\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :accessor} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :reader} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type\/} $\vert$ \cr
\+&&{\tt :initform} {\it form\/} $\vert$ \cr
\+&&{\tt :initialize-only} {\it flag\/} $\vert$\cr
\+&&{\tt :type} {\it type-specifier\/} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessor-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :reader-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol\/} \brac{boa-arglist\/}) $\vert$\cr
\+&&({\tt :uninstantiable} {\it flag\/}) $\vert$ \cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform}{\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject

\label Arguments:

The {\it class-name\/} argument is a non-{\bf nil} symbol.  It becomes the 
name of the new class.  If a class with the same name already exists, the
definition of that class is replaced.

Each {\it super-class-name\/} argument is a non-{\bf nil} symbol.
The new class will inherit slots and methods from each of its superclasses,
from their superclasses, and so on.
% characteristics (such as slots) and behavior (such as 
% methods) from each of its superclasses (and from their superclasses).
Each {\it super-class-name\/} argument must refer to a user-defined class, 
not to a built-in class.

Each {\it slot-spec\/} argument is the name of the slot or a list consisting
of the slot name followed by zero or more slot options.  The {\it slot-name\/}
argument is a symbol that can be used as a Common Lisp variable name.

%{\it slot-spec\/} can be a list of the slot name and its {\it
%default-value\/}, which can be any form.  When an instance is made and
%no initial value for this slot is provided as an argument to {\bf
%make-instance}, the slot is initialized to the value of this form.  The
%{\it default-value\/} is evaluated every time it is used. 

The following {\it slot-options\/} are available:

\beginlist

\item{\bull} 
The {\bf :accessor} option specifies that a method is to be
defined on the generic function named {\it generic-function-name\/} to
read the value of the given slot and that a method is to be defined on the
setf generic function named {\it generic-function-name} to be
used with {\bf setf} to modify the value of the slot.
The {\it generic-function-name\/} argument is a non-{\bf nil} symbol.
The {\bf :accessor} option may be specified more than once for a given
slot.

\item{\bull}
The {\bf :reader} option specifies that a method is to be
defined on the a generic function named {\it generic-function-name\/}
to read the value of the given slot.  The {\it
generic-function-name\/} argument is a non-{\bf nil} symbol.  The {\bf
:reader} option may be specified more than once for a given slot.

\item{\bull}
The {\bf :allocation} option is used to specify where storage is to be
allocated for the given slot.  Storage for a slot may be static or dynamic;
it may be located in the class instance or in the class object itself.
The value of the {\it allocation-type\/}
argument can be one of the following keywords: {\bf :instance}, {\bf :class},
{\bf :dynamic}, or {\bf :none}.  The {\bf :allocation} option may be
specified at most once for a given slot.  If the {\bf :allocation} option
is not specified, storage for the slot is allocated in the class instance.

\beginlist

\itemitem{--}
If the allocation type is {\bf :instance}, storage for the slot is allocated
in each class instance.  

\itemitem{--}
If the allocation type is {\bf :class}, storage for the slot is allocated
in the class object created by the {\bf defclass} form.  The value of
the slot is shared by all instances of the class.  Any subclass of this
class will share this same slot (storage) unless the {\bf defclass} form
for that subclass specifies a slot of the same name.

%[The useful part of this paragraph should go elsewhere--in the concepts
%document.]
%{\bf :allocation :class} Storage is allocated in the class.  Thus a
%single value for this slot is shared by all instances.  Class slots
%(like other slots) are inherited by subclasses of this class.  The state
%associated with a class slot is stored only where it is explicitly
%specified in the class.  If a local description of a slot is provided,
%it completely overrides an inherited description of a component class. 

\itemitem{--}
If the allocation type is {\bf :dynamic}, storage is allocated in the instance
the first time the slot is used.  This option allows infrequently-used slots
to occupy storage only if necessary.
%If the slot is initialized with a keyword
%argument to {\bf make-instance}, the slot is allocated then.  If the
%first access is a read, then storage is allocated and the default value
%specified in the {\bf defclass} form, if any, is stored in the slot and
%returned.  If the first access is a {\bf setf}, then storage is
%allocated and the value is stored in the slot and returned.  

\itemitem{--}
If the allocation type is {\bf :none}, no storage is allocated for the
slot and the slot will not exist in instances of the given class.  This
option may be used to override the inheritance of slots defined by
a superclass.

\endlist 

\item{\bull}
The {\bf :initform} option is used to provide
an initial value form to be used in the initialization of the
slot.  This form is evaluated every time it is used.  
The {\bf :initform} option may be specified at most once for a
given slot.

\item{\bull}
The {\bf :initialize-only} option is used to specify that the contents
of the given slot may not be altered after the instance is created.
The default value of the {\bf :initialize-only} option is {\bf nil}.

\item{\bull}
The {\bf :type} option specifies the type of the slot contents.  The
argument to {\bf :type} is a type specifier.  If the {\bf :type}
option is specified, the slot contents must be of the given type.

%\item{\bull}
%The {\bf :initable} option specifies a non-{\bf nil} symbol to be used
%to specify an initial value of this slot, when a new instance is being
%made.  This symbol can be supplied as an {bf \&key} argument to {bf
%make-instance}.  (This is still under discussion.) 
%The {\bf :initable} option may be specified more than once for a given slot.

\endlist

Each {\it class-option\/} is an option that refers to the class as a whole
or to all class slots.
The following options are available:

\beginlist
\item{\bull}
The {\bf :accessor-prefix} option specifies that, for each
slot, a method to read the value of the slot is to be defined on
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  Similarly, a method to be used with the macro {\bf
setf} to modify the value of the slot is to be defined on the setf
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  These accessor functions are interned in the
package that is current at the time the {\bf defclass} form is
processed.  If the prefix is {\bf nil}, the names of the accessor
functions are the symbols that are used as the slot names.  The {\bf
:accessor-prefix} option may be specified more than once.

\item{\bull} 
The {\bf :reader-prefix} option specifies that,
for each slot, a method to read the value of the slot is to be defined
on generic function named {\it string-or-symbol}{\bf -} followed by
the name of the slot.  These reader functions are interned in the
package that is current at the time the {\bf defclass} form is
processed.  If the prefix is {\bf nil}, the names of the reader
functions are the symbols that are used as the slot names.  The {\bf
:reader-prefix} option may be specified more than once.

\item{\bull}
The {\bf :constructor} option causes a constructor function to be
generated automatically.  The constructor function is used to make
new instances of the class.
The {\it symbol\/} argument is a non-{\bf nil} symbol that
specifies the name of the constructor function.
If the {\it boa-arglist\/} argument is present, it describes the arguments
to the constructor.  The {\it boa-arglist\/} argument of {\bf defclass}
is identical to that of {\bf defstruct}.
%In the simplest case, the elements of {\it arglist\/} are the slot
%names themselves ({\it not\/} keywords) in the order in which they are to
%occur as arguments.  The keywords {\bf \&optional}, {\bf \&rest}, and
%{\bf \&aux} may also be used in {\it arglist\/}.  Any {\bf \&optional} and
%{\bf \&aux} arguments for which no initialization forms have been specified
%in {\it arglist\/} are not set to {\bf nil} as they would be in a lambda list.
%The initial value of any {\bf \&optional} argument for which no initialization
%form is specified in {\it arglist\/} is taken from the
%{\it initform\/} argument given for the slot description.  The initial value
%of any {\bf \&aux} argument for which no initialization form is specified in
%{\it arglist\/} is undefined.
The {\bf :constructor} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :default-init-plist} option is used to specify default values
%that are to be used when making an instance of the class.  For
%example, a class might specify a default value to use to initialize a
%slot inherited from one of its superclasses.  Each {\it keyword\/}
%must be a valid keyword argument to {\bf make-instance}.  Each {\it
%argument\/} is a form that provides the default value for that keyword
%argument if it is not supplied.  The user can override the defaults in
%the {\bf :default-init-plist} by providing keyword arguments to {\bf
%make-instance}.  The {\it arguments\/} are evaluated every time they
%are used.  The {\bf :default-init-plist} option may be specified more
%than once.  This option is still under discussion; it is not yet clear
%whether it should be in the standard.

\item{\bull} 
A documentation string may be attached to the class name
by specifying the {\bf :documentation} argument.  The documentation
type for this string is {\bf type}.  The form {\tt (documentation {\it
class-name\/} 'type)} may be used to retrieve the documentation
string.  The {\bf :documentation} option may be specified at most once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :init-keywords} option is used to
%specify that the given keywords may be used as keyword arguments to
%{\bf make-instance} when an instance of this class is to be created.
%It is not necessary to provide this argument to make it possible
%to initialize slots; that is done with the {\bf :initable-slots} option.
%The {\bf :init-keywords} option is used in conjunction with user-supplied
%methods {\bf make-instance}.  If a {\bf make-instance} method accepts
%an argument, it must be made an allowed keyword argument to {\bf make-instance}
%by using this option.
%The {\bf :init-keywords} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :initable-slots} option is used to specify that it is allowed
%to initialize all
%slots of this class.  The initialization can be done by providing the
%keyword with the same name as the slot, followed by the slot's initial
%value as an argument to {\bf make-instance} or by including the keyword
%and value in the {\bf :default-init-plist}.

\item{\bull}
The {\bf :uninstantiable} option is used to specify whether it is
possible to directly instantiate the new class with {\bf make-instance}.
If the value of {\bf :uninstantiable} is true, the class cannot be instantiated
and is termed an {\bit abstract class}.  The default value of {\bf
:uninstantiable} is {\bf nil}.  The {\bf :uninstantiable} option may be 
specified at most once.

\item{\bull}
The {\bf :metaclass} option may be used to specify that the new class
is to have a different class than the default provided by the system
(the class {\bf class}).  The {\it class-name} argument is the name of
a class that is capable of being the class of a class.  The {\bf
:metaclass} option may be specified at most once.

%\item{\bull}
%The {\bf :predicate} option causes a predicate function
%named {\it symbol\/} to be generated automatically.  The {\it
%symbol\/} argument must be a non-{\bf nil} symbol.  The predicate
%function takes one argument, an object.  It returns true if the object
%is of this class, otherwise it returns {\bf nil}.  The {\bf :predicate}
%option may be specified more than once.

\endlist

\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If a class of the same name already exists, that class is redefined as
follows:

\beginlist
\item{\bull}
A copy of the class object is created.  This copy is named {\tt
|obsolete-{\it class-name\/}|}, where {\it class-name\/} is the name of
the original class; this copy is {\bf equal} to the original class
object.

\item{\bull}
 All instances of the original class are made to point to the
``obsolete'' class object.

\item{\bull}
The original class object is modified to reflect the specified
changes; this modified class object is {\bf eq} to the original.

\item{\bull}
When the instances of the obsolete class
are accessed, they are updated to reflect the new class definition.

\endlist

Each class has a superclasses lattice composed of all its immediate
superclasses, the immediate superclasses of these superclasses, and so
on.  This lattice is used to compute the class precedence list of the
class.  It is discussed in the section ``Determining the Class
Precedence List.''

Note the following rules of {\bf defclass}:

\beginlist

\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.

\item{\bull}
All the superclasses of a class must be defined before it is permitted
to make an instance of the class.

\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.

\item{\bull}
All the superclasses of a class must be defined before it is
permitted to evaluate or compile a {\bf with-slots} that uses that class.

\endlist


Slot options and class options are inherited by a class from its
superclasses.   However, it is possible to override an option
that would be inherited from a superclass simply by specifying
that option in the {\bf defclass} form.  [This needs to be made more
precise.]

Some implementations might add other options to {\bf defclass}.
Therefore it is required that all implementations signal an error if
they observe a class option or a slot option that is not implemented
locally.

If no default value for a slot is specified either in a {\bf
defclass} or a {\bf make-instance} form, the initial value of the
slot is unspecified.

It is valid to specify more than one accessor, reader, and initialization
keyword for a slot.

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or {\bf
with-slots} using {\bf :use-accessors nil}.

The {\bf :accessor} and {\bf :reader} slot options may appear more than once.

The {\bf :accessor-prefix}, {\bf :constructor}, and {\bf
:reader-prefix} class options may appear more than once:

No other slot option or class option may appear more than once in a
single {\bf defclass} form.

\label See Also:

{\bf slot-value

with-slots}

\endcom



\begincom{defgeneric-options}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options} is used to specify options and
declarations that pertain to a generic function as a whole.

The generic function is stored in the symbol-function cell of {\it name}.
If {\tt (fboundp {\it name\/})} is {\bf nil}, a new generic function 
is created.  If {\tt (symbol-function {\it name\/})} is a generic function,
that generic function is modified.  If neither of these conditions holds,
{\bf defgeneric-options} signals an error.

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options} {name lambda-list \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it
argument-precedence-alist\/}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}

\label Arguments:

The {\it name} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

\beginlist
\item{\bull}
No {\bf \&aux} variables are allowed. 

\item{\bull}
Optional and keyword arguments may not have default initial value forms
or use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters. 
\endlist

The following options are provided:

\beginlist

\item{\bull}
The {\bf:argument-precedence-order} option is used to specify the
order in which the required arguments in a call to the generic
function are tested for specificity when selecting a particular
method.  By default, all required arguments are considered from left
to right; each required argument has precedence over those to its
right.  The {\it argument-precedence-alist} argument is an association
list.  Each pair in this association list consists of a parameter name
and an integer (greater than or equal to 0 and less than the number of
required arguments) that indicates the position of the corresponding
argument in the precedence order.  A value of 0 indicates the highest
precedence.  A full and unambiguous precedence order must be supplied
or an error is signalled.

\item{\bull}
The {\bf declare} option is used to specify declarations that pertain
to the generic function.  These declarations do not apply to the
methods.  Declarations that have semantic effect ({\bf special}, {\bf
inline}, and {\bf notinline} declarations) are not permitted.  Other
types of declarations are advice to the compiler that may or may not
affect the implementation of the generic function.  Individual
implementations are not required to pay attention to them.  It is
expected that the main use of this facility will be for {\bf ftype}
declarations.  If an implementation notices a declaration that it does
not support and that has not been proclaimed as a non-standard
declaration name, it should issue a warning.

\item{\bull}
The {\bf :documentation} argument associates a documentation string
with the generic function.   The documentation type for this string
is {\bf function}.  The form
{\tt (documentation {\it generic-function-name\/} 'function)}
may be used to retrieve this string.

\item{\bull}
The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default provided
by the system (the class {\bf generic-function}).
The {\it class-name\/} argument is the name
of a class that can be the class of a generic function.

%\item{\bull}
%The {\bf :interface} option is still under discussion.
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%                Defines a function that runs instead of the generic
%                dispatch.  This is completely transparent to anyone calling
%                the generic function.  Such a prologue function can be used
%                to rearrange the arguments, to standardize the arguments
%                before the methods see them, to default optional arguments,
%                to do the shared non-generic portion of an operation, or
%                for any other purpose.
%
%                Inside the forms you can trigger the generic dispatch with
%                (call-next-method args...) or (apply-next-method args...).
%		apply-next-method treats the last argument as a list of
%                arguments just like apply.  ]
%
%\item{\bull}
%(:method-arguments {lambda-list}+)
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%		This option is under discussion. 
%                You can use this option to specify that the methods accept
%                different arguments than does the generic function itself.
%                By default, the methods receive the same arguments that are
%                specified at the top of the defgeneric form.   If
%		:interface is also specified, it provides the
%		translation from generic-function arguments to 
%		method-arguments.   If :interface is not specified, the
%		arguments are permuted according to matching names, and
%		all names in the :method-arguments lambda-list must also
%		appear in the generic-function's lambda-list.   For
%                example:
%			
%		(defgeneric foo (x y \&optional z) 
%                   (:method-arguments y x z)) ]

\item{\bull}
The {\bf :method-class} option is used to specify that all methods for
this generic function are to have a different class than the default
provided by the system (the class {\bf method}).
The {\it class-name\/} argument is the name of a
class that is capable of being the class of a method.

\item{\bull}
[The {\bf :method-combination} option is still under discussion.]
%
%(:method-combination name {argument}*)
%                Indicates that the generic function uses the type of method
%                combination named by name.  The arguments depend on the
%                type of method combination.  The most common argument is
%                one to specify the order of methods, which is either
%                :most-specific-first or :most-specific-last.  The default
%                method combination type is :daemon, with the
%                :most-specific-first order.
\endlist

\label Values:

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[What happens when {\bf defgeneric-options} causes the options of an existing
generic function to be changed needs to be spec'd out.]

If a {\bf defgeneric-options} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf defgeneric-options}, an error is signalled.  
[Note:  other kinds of errors still need to be discussed.]

[Needs discussion about compatibility of methods.]

Some implementations might add other options to {\bf defgeneric-options}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\endcom




\begincom{defgeneric-options-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options-setf} is used to define a {\bf setf} generic
function.
A {\bf setf} generic function is called in an expression such as
{\tt (setf ({\it generic-function-name arguments}) {\it newvalue})}.

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options-setf} {name lambda-list setf-lambda-list \star{\curly{option}}}

{\it setf-lambda-list\/}::$=$ \paren{variable-name\/}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-alist\/}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip1pc!\null

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is identical to the
{\it lambda-list\/} argument of {\bf defgeneric-options}.

The keyword options are the same as for {\bf defgeneric-options}.

The {\it variable-name\/} argument in the {\bf setf} lambda list
is the name of the variable that gets bound to the
value of the {\it newvalue\/} form in the expression
{\tt (setf {\it place newvalue})}.
 
\label Values:

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[The internal operation of this function needs to be spec'd out.
%--Gregor to provide.
]

[Needs discussion about compatibility of methods.]

\label See Also:

{\bf defgeneric-options

defmethod}

\endcom




\begincom{define-method-combination}\ftype{Macro}

\label Purpose:

The macro {\bf define-method-combination} is used to define new types
of method combination.

At present the details of {\bf define-method-combination} and related
functions are under discussion.

%\label Syntax:

%\label Arguments:

%\label Values:

%\label Examples:

%\label Remarks:

\endcom



\begincom{defmethod}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod} defines a new method on a generic
function.

If no generic function is currently named by the symbol {\it name\/},
a generic function is created using default parameter specializers
({\bf t}), the default argument precedence order (arguments are in
order of decreasing precedence), the default generic function class
(the class {\bf generic-function}), and the default method class (the
class {\bf method}).

The argument list of the method must be congruent with the argument 
list of the generic function.  If this condition does not hold, an error is
signalled.  See ``Generic Functions and Methods" for 
a definition of congruency in this context.  

\label Syntax:

\Defmac {defmethod} {name
\vtop{\hbox{\star{\curly{method-combination-identifier\/}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-combination-identifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol that
names the generic function on which the method is defined.
%was: the generic function being specialized.   

The {\it method-combination-identifier\/} is the object that is used
by method combination to identify the given method.  A method
combination identifier is a non-{\bf nil} atom.  The precise method
combination type may further restrict what a method combination
identifier may be.  [The details of method combination and method
combination identifiers are still under discussion.]

The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda list except that parameters for required arguments may
be replaced by specialized parameters.  A specialized parameter is a
list {\tt ({\it variable-name parameter-specializer\/})}.  Only
required parameters may be specialized.
A parameter {\it specializer\/} 
is a symbol that names a user-defined class, a structure defined by
{\bf defstruct} if the {\bf :type} option was not used, or a class
that corresponds to a Common Lisp type specifier.   Note that
not all Common Lisp types have a corresponding
class.   The section ``Generic Functions and Methods"
lists the Common Lisp types that have corresponding
classes.  A parameter specializer can also be {\tt (quote {\it object\/})}.
Such a parameter specializer indicates that this corresponding argument must
be {\bf eql} to the quoted object for the method to be applicable.  
If no parameter specializer is specified for a given required parameter,
the parameter specializer for that parameter defaults to {\bf t}.
A method, all of whose required arguments, have {\bf t} parameter
specifiers is termed a {\bit default method}.  Such a method is selected
when no more specific method for the generic function is applicable.

\label Values:

The result of {\bf defmethod} is the list consisting of the generic
function name, a list of the method combination identifiers, and a list
of the lambda list specializers that is equivalent to the value returned
by {\bf lambda-list-specializers} when applied to the specified lambda
list.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The class of the method object that is created is that given by the
method class option of the generic function on which the method is defined.

[To be discussed: ``replacing'' or ``redefining'' a method.]

\label See Also:

{\bf get-method

lambda-list-specializers}

\endcom


\begincom{defmethod-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod-setf} defines a method for a {\bf setf} generic
function.  A {\bf setf} generic function is called in an expression such as: 
{\tt (setf ({\it generic-function-name arguments\/}) {\it new-value\/})}. 

\label Syntax:

\Defmac {defmethod-setf} {name
\vtop{\hbox{\star{\curly{method-combination-identifier\/}}}
\hbox{specialized-lambda-list specialized-setf-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-combination-identifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-lambda-list\/}::$=$ (\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The arguments {\it name\/}, {\it
method-combination-identifier\/}, and {\it specialized-lambda-list\/}
are the same as for {\bf defmethod}.

The {\it specialized-setf-lambda-list\/} argument is the same as {\it
specialized-lambda-list\/} except that for now there can be only one
parameter.  In other words, {\it setf-lambda-list\/} is a lambda list
containing exactly one required parameter, which may be specialized.
It is either {\tt ({\it variable-name\/})} or {\tt (({\it variable-name
parameter-specializer\/}))}.  %[Do we want to clarify this ``for now''
stuff?]

\label Values:

The result of {\bf defmethod-setf} is the list consisting of the generic
function name, a list of the method combination identifiers, and list
of the lambda list specializers that is equivalent to the value returned
by {\bf lambda-list-specializers} when applied to the specified lambda
list, and a list of the setf lambda list specializers.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}\ftype{Generic function}

\label Purpose:

The Common Lisp function {\bf describe} is replaced by a generic
function.  The function {\bf describe} prints information about a
given object on the standard output.

Each implementation is required to replace its former implementation of
{\bf describe} with one or more methods.  In particular, there must
be methods provided for the classes {\bf t} and {\bf object}.
Implementations are free to add methods for other classes.

Users can also write methods for {\bf describe}.  These methods must
conform to the definition of {\bf describe} as specified in {\it
Common Lisp the Language}.

\label Syntax:

\Defgen {describe} {object}

\label Arguments:

The argument of {\bf describe} may be any Common Lisp object. 

\label Values:

The function {\bf describe} returns no values.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{documentation}\ftype{Generic Function}

\label Purpose:

The Common Lisp function {\bf documentation} is replaced by a
generic function.
The first argument is a generic function, a method, a class object, or
a symbol.

If the first argument is a generic function, {\bf documentation} returns the
documentation string for the generic function.
If the first argument is a method, the documentation string of the method
is returned.
If the first argument is a class object, the documentation string for the
class is returned.

If the first argument is a symbol, the second argument must be specified
and {\bf documentation} returns the documentation string of the given type.
The {\it doc-type\/} argument is a symbol.  It can be one of the following
types: {\bf variable}, {\bf function}, {\bf structure}, {\bf type}, and
{\bf setf}.

If no documentation is associated with the given object, {\bf documentation}
returns {\bf nil}.

%[See Patrick's comments.]

\label Syntax:

\Defgen documentation {x {\opt} doc-type}

\label Values:

The documentation string is returned.
If no documentation is associated with the given object, {\bf documentation}
returns {\bf nil}.

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function, method, or class.

\endcom



\begincom{generic-function-lambda-list}\ftype{Generic function}

\label Purpose:

The generic function {\bf generic-function-lambda-list} returns the
lambda list of its argument from which default values for {\bf
\&optional} and {\bf \&key} parameters and supplied-p parameters have
been removed.

\label Syntax:

\Defgen {generic-function-lambda-list} {function-or-generic-function}

\label Arguments:

The argument to {\bf generic-function-lambda-list} is a function,
generic function, or a symbol that names a function or generic
function.

\label Values:

The result of {\bf generic-function-lambda-list} is a copy of the
lambda list of its argument from which default values for {\bf
\&optional} and {\bf \&key} parameters and supplied-p parameters have
been removed.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

There is a related function named {\bf function-parameters} that is
being considered for Common Lisp.

\endcom


\begincom{generic-function-method-combination-type}\ftype{Generic function}

\label Purpose:

The generic function {\bf generic-function-method-combination-type}
returns the method combination type for the given generic function.

[The details of this function are currently under discussion.]

\label Syntax:

\Defgen {generic-function-method-combination} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic
function or a symbol that names a generic function.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



%\begincom{generic-function-p}\ftype{}
%
%\label Purpose:
%
%The predicate {\bf generic-function-p} is true if its argument is a
%generic function, otherwise it is false.
%
%\label Syntax:
%
%\Defun {generic-function-p} {object}
%
%\label Values:
%
%A non-{\bf nil} value is returned if the argument is a generic function
%object, otherwise the result is {\bf nil}.
%
%\label Examples:
%
%\screen!
%\endscreen!
%
%\endcom



\begincom{get-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf get-method} takes a generic function and returns the
method object that has the given method combination identifiers and
parameter specializers.  If no such method exists, {\bf get-method}
signals an error.

\label Syntax:

\Defgen {get-method} {generic-function method-combination-identifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.  An error is signalled if no
such function exists.

The {\it method-combination-identifiers\/} argument is a list of the
method combination identifiers for the method.

The {\it specializers\/} argument is a list of the parameter specializers
for the method.  It must correspond in length to the number of required
arguments of the generic function.  This means that to obtain the default
method for a given generic function, a list of {\bf t}'s corresponding in
length to the number of required arguments of that generic function must
be given.

%If {\it specializers\/} is {\bf nil}, the
%default method function for that generic function is returned.

\label Values:

The result of {\bf get-method} is the method object with the given
method combination identifiers and parameter specializers.  If no such
method object exists, {\bf get-method} signals an error.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{get-setf-generic-function}\ftype{Function}

The function {\bf get-setf-generic-function} takes a symbol for which
a setf generic function has been defined by either {\bf
defmethod-setf} or {\bf defgeneric-options-setf} and returns a generic
function object.  This object is the generic function that is called
when the {\tt (setf ({\it generic-function-name arguments\/})
{\it newvalue\/})} is invoked.

[More details to be provided by Gregor.]

\label Syntax:

\Defun {get-setf-generic-function} {name}

\label Arguments:

The {\it name\/} argument is a symbol for which a setf generic
function has been defined.  If no such setf generic function has been
defined, an error is signalled.

\label Values:

The function {\bf get-setf-generic-function} returns a generic function
object.
This object is the generic function that is called
when the {\tt (setf ({\it generic-function-name arguments\/})
{\it newvalue\/})} is invoked.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{lambda-list-specializers}\ftype{Function}

\label Purpose:

The function {\bf lambda-list-specializers} takes an ordinary lambda
list or a specialized lambda list and returns a list containing the
parameter specializers for all required arguments.  The specializer
{\bf t} is returned for any required lambda list argument for which no
parameter specializer was given.

\label Syntax:

\Defun {lambda-list-specializers} {specialized-lambda-list}

\label Values:

The result of {\bf lambda-list-specializers} is a list of the parameter
specializers for all required arguments in the given lambda list.

\endcom


\begincom{make-generic-function}\ftype{Function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :lambda-list :argument-precedence-order}
\hbox{ :declare :documentation :method-combination-type}
\hbox{ :generic-function-class :method-class}}}

\label Arguments:

The {\bf :lambda-list} argument is a lambda list of the type that may be
given to {\bf defgeneric-options}.

The following arguments have the same semantics as the corresponding
arguments of {\bf defgeneric-options} although their syntax may differ:

\beginlist

\item{\bull}
The {\bf :argument-precedence-order} argument is an association list.
Each pair in this association list consists of the parameter name of
one of the required parameters (as specified by the {\bf :lambda-list}
argument) and an integer (greater than or equal to 0 and less than the
number of required arguments) that indicates the position of the
corresponding argument in the precedence order.

\item{\bull}
The {\bf :method-combination-type} argument is still under discussion.
% a symbol.

\item{\bull}
The {\bf :documentation} argument is a string.

\item{\bull}
The {\bf :declare} argument is a list of declaration specifiers.

\item{\bull}
The {\bf :generic-function-class} argument is a class or the name of a class.

\item{\bull}
The {\bf :method-class} argument is a class or the name of a class.
\endlist


\label Values:

The result of {\bf make-generic-function} is a generic function object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function {\bf make-generic-function} is the
programmatic interface to {\bf defgeneric-options}.

\label See Also:

{\bf defgeneric-options}

\endcom

\begincom{make-instance}\ftype{Function}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class or a symbol that names a class.

\label Values:

The new instance is returned.

\label Remarks:

[Discussion of initialization to go here.]

It is not possible to make an instance of a class whose class is
{\bf built-in-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf built-in-class}, 
{\bf make-instance} signals an error.

It is not possible to make an instance of class created with {\bf defclass}
if the {\bf :instantiable} option was {\bf nil}.  An error is signalled in
this case.

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

\label See Also:

{\bf class-of}

\endcom



\begincom{make-method}\ftype{Function}

\label Purpose:

The function {\bf make-method} creates and returns a method object.

\label Syntax:

\Defun {make-method} {method-combination-identifiers specializers function}

\label Arguments:

The {\it method-combination-identifiers\/} argument is a list of the method
combination identifiers for the method.
%A method combination identifier is a non-{\bf nil} symbol.

The {\it specializers\/} argument is a list of the parameter
specializers for the method.

The {\it function\/} argument is the method function.  

The length of the list of specializers must be equal to
the number of required arguments of the method function.

\label Values:

The function {\bf make-method} returns the resulting method object.
\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod

add-method}

\endcom



\begincom{print-object}\ftype{Generic function}

\label Purpose:

The generic function {\bf print-object} outputs the printed
representation of an object onto a stream.  The function {\bf
print-object} is called by the print system; it should not be called
by the user.

Each implementation is required to provide methods for the classes
{\bf t} and {\bf object}.  Implementations are free to add methods
for other classes.  Users can also write methods for {\bf print-object}.

\label Syntax:

\Defgen {print-object} {object stream}

\label Arguments:

[To be written.]

\label Values:

[To be written.]

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[This section needs to be rewritten.]

Methods for {\bf print-object} must obey the print control special
variables described in {\it Common Lisp the Language}.  The
specific details are:

*PRINT-ESCAPE*  Each method must implement this.

*PRINT-PRETTY*  This can be ignored by most methods other than the one for
                lists.

*PRINT-CIRCLE*  This is handled by the printer and can be ignored by
                methods.

*PRINT-LEVEL*   The printer takes care of this automatically, provided that
                each method handles exactly one level of structure and
                calls write (or an equivalent function) recursively if
                there are more structural levels.  The printer's decision
                of whether an object has components, and therefore should
                not be printed when the printing depth is not less than
                *PRINT-LEVEL*, is implementation-dependent.  In some
                implementations its PRINT-OBJECT method is not called, in
                others the method is called and the determination that the
                object has components is based on what it tries to output
                to the stream.

*PRINT-LENGTH*  Methods that produce output of indefinite length must obey
                this, but most methods other than the one for lists can
                ignore it.

*PRINT-BASE*, *PRINT-RADIX*, *PRINT-CASE*, *PRINT-GENSYM*, and
*PRINT-ARRAY* apply to specific types of objects and are handled by the
methods for those objects.

In general, the printer and the PRINT-OBJECT methods should not rebind the
print-control variables as they recurse through the structure, but this is
necessarily implementation-dependent.

In some implementations the stream argument passed to a PRINT-OBJECT method
is not the original stream, but is an intermediate stream that implements
part of the printer, so methods should not depend on the identity of this
stream.

All of the existing printing functions (write, prin1, print, princ,
pprint, write-to-string, prin1-to-string, princ-to-string, the format
{\tt ~}{\bf S} and {\tt ~}{\bf A} operations, and the format {\tt
~}{\bf B}, {\tt ~}{\bf D}, {\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf
G}, {\tt ~}{\bf \$}, {\tt ~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf
X} operations when they encounter a non-numeric value) are required to
be changed to go through the PRINT-OBJECT generic function.  Each
implementation is required to replace its former implementation of
printing with one or more PRINT-OBJECT methods.  Exactly which classes
have methods for PRINT-OBJECT is not specified; it would be valid for
an implementation to have one default method that is inherited by all
system-defined classes.

References: See MIT AI Memo 816, December 1984, by Richard C. Waters for a
discussion of PP, one of the better designed Lisp printers.  It handles
*PRINT-LEVEL* and *PRINT-LENGTH* invisibly to the PRINT-OBJECT methods.
See also the inconclusive discussion on printing, *PRINT-LEVEL*, and
recursion on the Common-Lisp mailing list around 21 November 1985 for
additional background.

\endcom



%\begincom{remove-class}\ftype{}
%
%\label Purpose:
%
%\label Syntax:
%
%\Defun {remove-class} {class}
%
%\label Arguments:
%
%\label Values:
%
%\label Examples:
%
%\endcom



\begincom{remove-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf remove-method} removes a method from a generic
function.  It modifies the specified generic function and returns the
modified generic function as its result.
If this method is not a method of the generic function, an error is signalled.

\label Syntax:

\Defgen {remove-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.    If there is no such generic 
function, an error is signalled.

The {\it method\/} argument is a method object.  The argument list of
the method function must be congruent with the argument lists of any
other methods associated with the generic function or with the
lambda list of the generic function.

\label Values:

The result of {\bf remove-method} is the modified generic function.
% method object with the given
%method combination identifiers and parameter specializers.  If no such
%method object exists, {\bf remove-method} returns {\bf nil}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

\label See Also:

{\bf
get-method

add-method}

\endcom



%\begincom{remove-setf-method}\ftype{Function}
%
%\label Purpose:
%
%The function {\bf remove-setf-method} removes the {\bf setf} method
%for the given name, method combination identifiers, and parameter
%specializers from the corresponding generic function.
%
%The method {\bf remove-setf-method} returns the given method object if it 
%succeeds and {\bf nil} if there is no such method.
%
%\label Syntax:
%
%\Defun {remove-setf-method} {generic-function method-combination-identifiers
%specializers setf-specializers}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is a generic function or the name
%of a generic function.
%
%The {\it method-combination-identifiers\/} argument is a list of the
%method combination identifiers for the method.
%
%The {\it specializers\/} argument is a list of
%the parameter specializers for the arguments of the
%method that is to be removed.  If the {\it specializers\/}
%list contains fewer elements than the lambda list of the corresponding
%generic function, the remaining elements are considered to be {\bf t}.
%
%The {\it specializers\/} list can be obtained from a
%{\bf defmethod} lambda list by use of the function 
%{\bf lambda-list-specializers}.
%
%\label Values:
%
%The result of {\bf remove-setf-method} is the method object with the
%given method combination identifiers and parameter specializers.  If
%no such method object exists, {\bf remove-setf-method} returns {\bf
%nil}.
%
%\label See Also:
%
%{\bf lambda-list-specializers
%
%remove-method
%
%defmethod}
%
%\endcom


\begincom{slot-value}\ftype{Function}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot unless the slot is initialize-only.  Attempting to change the
value of an initialize-only slot causes an error to be signalled.

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}\ftype{Macro}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for referring to
slots as though they were variables.  Within such a context the value
of the slot can be specified by using its slot name, as if it were a
lexically bound variable.  Both {\bf setf} and {\bf setq} can be used
to set the value of the slot.  The macro {\bf with-slots} can be used
inside a method or inside of any function.

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
unless the value of the {\bf :use-accessors} argument is {\bf nil}.

\label Syntax:  

\Defmac {with-slots} {\paren {\star{\curly{instance-form $\vert$ \paren{instance-form \star{option}}}}} \star{\form}}

{\it option\/}::$=$  {\tt\vtop{\hbox{:use-accessors {\it flag\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The form {\it instance-form\/} must evaluate to an instance of a
class.  Each such form is evaluated exactly once, upon entry to the
body of the {\bf with-slots} form.  The {\it instance-form\/} forms
are evaluated in the order in which they appear.

It is necessary that the class of the instance can be determined.
Either {\it instance\/} must be the name of a specialized parameter in
the lambda-list of a method lexically containing this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.

The following keyword options are available:

\beginlist

\item{\bull}
The {\bf :class} option is used to specify the class or a superclass
of the instance.  Its argument is the name of a class.  This option is
necessary if the class of the instance cannot be determined from the
lambda list of a method lexically containing the {\bf with-slots}
form or if the {\bf with-slots} form does not occur within a method
form.  If the {\bf :class} option is used an error is signalled if the
class of the instance is not a subclass of the specified class.

\item{\bull}
The {\bf :prefix} option is used to generate a variable name by which
the given slot may be referenced.
This name is given by {\it prefix-string\/}{\bf -} followed by the slot
name.  It causes a symbol of the given name to be created and interned in the package that is current at the time the
{\bf with-slots} form is processed. 
This option can be used to keep separate two instances whose slot names
overlap, such as two instances of the same class or two instances that
have a common superclass.

\item{\bull}
The {\bf :use-accessors} option is used to specify whether accessing a
slot is performed using the accessor function generated by {\bf defclass}
or by the function {\bf slot-value}.  If {\bf :use-accessors} is {\bf t},
the accessor function generated by defclass is used to access the slots; this
means that any methods written for the accessor are also run.
If {\bf :use-accessors} is {\bf nil}, {\bf with-slots} accesses the
slots using {\bf slot-value} instead of the accessor.
If accessors for the slot were not specified in the relevant {\bf defclass}
form, then the value of {\bf :use-accessors} should be specified as {\bf nil}.
The default value of {\bf :use-accessors} is {\bf t}.

\endlist

\label Values:

The value of the {\bf with-slots} form is the value returned by
the last form in its body. 

\label Examples:

\screen!

(defclass point () ((x 0) (y 0))
  (:accessor-prefix point-))

(defmethod move ((p point) dx dy)
  (with-slots (p)  ;; p is known as a point from the method args
    (setf x (+ x dx) y (+ y dy))))

(defmethod move ((p point) dx dy)
  (with-slots ((p :use-accessors nil))
    (setf x (+ x dx) y (+ y dy))))

(defmethod make-same-height ((p1 point) (p2 point))
  (with-slots ((p1 :prefix p1-) (p2 :prefix p2-))
    (setf p1-y p2-y)))

(defmethod make-horizontal ((l line))
   (let ((left (left-point l)) (right (right-point l)))
     (with-slots ((left  :class point :prefix left-)
                  (right :class point :prefix right-))
       (setf left-y right-y))))

\endscreen!

%\label Remarks:
%
%It is an error if the class of {\it instance} cannot be inferred from
%the lexical context in which it occurs.  If any ambiguity is detected,
%{\bf with-slots} signals an error.
%
\endcom
\endChapter
\bye